home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / os2 / bnews093.zip / bnews.doc next >
Text File  |  1996-10-31  |  12KB  |  330 lines
  1.  
  2.                     B I N A R Y   N E W S   G A T H E R E R
  3.                     =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  4.                        Copyright 1996 by Crown Software
  5.                                    Phil Crown
  6.                                pcrown@airmail.net
  7.                         http://web2.airmail.net/pcrown/
  8.  
  9.  
  10. THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  11. INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  12. FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  13. REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  14. SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  15. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  16. OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  17. WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  18. OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  19. ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  20.  
  21.  
  22. Contents
  23. =-=-=-=-
  24.  
  25.  1.  Overview
  26.  2   System Requirements
  27.  3.  Quick Start
  28.  4.  Configuration File
  29.  5.  Command Line Options
  30.  6.  Operation
  31.  7.  File Naming Mechanism
  32.  8.  Problems
  33.  9.  Future versions
  34. 10.  Registration
  35. 11.  History
  36.  
  37.  
  38. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  39. 1.  Overview
  40.  
  41. Binary News Gatherer is an OS/2 text mode application for downloading an
  42. overview and selected articles from binary news groups via NNTP.
  43.  
  44. See "History" at the end of this document for recent changes.
  45.  
  46.  
  47. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  48. 2.  System Requirements
  49.  
  50. This program uses longfilenames, therefore requires HPFS.
  51.  
  52. OS/2 Warp IAK (so32dll.dll and tcp32dll.dll).
  53.  
  54.  
  55. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  56. 3.  Quick Start
  57.  
  58. Place ocli.dll in a directory in your LIBPATH, or run bnews.exe from
  59. the same directory as ocli.dll.
  60.  
  61. Typical usage consists of following steps:
  62.  
  63.   1.  Edit bnews.ini (first time usage only) for your system.
  64.       See bnews.ini.
  65.  
  66.   2.  Download an overview of a group:  bnews /Cover /G<group> /H<host>
  67.       Overview is saved as <group>.over.txt.
  68.  
  69.   3.  Create a list of articles that you want to retrieve.  You must do
  70.       this with your favorite text editor.  Load the <group>.over.txt
  71.       file in your editor, and cut and paste the articles that you
  72.       want to get, save as <group>.get.txt
  73.  
  74.   4.  Download the articles:  bnews /Cart /G<group> /H<host>
  75.       Articles are saved in <group>.uue.
  76.  
  77.  
  78. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  79. 4.  Configuration File
  80.  
  81. Bnews.ini is the configuration file.  This file is not required, but it
  82. will save some typing at the command line.
  83.  
  84. The default configuration file is bnews.ini, in the same directory as
  85. bnews.exe.  To specify a different configuration file, use the /Imy.ini
  86. switch.
  87.  
  88. The configuration file can contain any valid Command Line Options,
  89. except; /I<my.ini>
  90.  
  91. See:  bnews.ini
  92.  
  93. Parameters on the command line override settings in the configuration
  94. file.
  95.  
  96.  
  97. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  98. 5.  Command Line Options
  99.  
  100. /C<command>   ART, OVER, NEW
  101.  
  102.               /CART   ARTICLE - Download articles listed in <group>.get.txt.
  103.  
  104.               /COVER  OVERVIEW - Download an overview of a group.
  105.  
  106.               /CNEW   NEWNEWS - Downloads only new articles since the
  107.                       last /cnew session was run.  The file
  108.                       bnews.newstime (in the same directory as
  109.                       bnews.exe) contains the time of last access for
  110.                       each group.
  111.  
  112. /G<group>     The full name of the news group to retrieve articles or an
  113.               overview from.
  114.  
  115.               /Galt.binaries.pictures
  116.               /Gmy.favorite.binaries.group
  117.  
  118. /H<hostname>  Your NNTP news server.
  119.  
  120.               /Hnews.your.net
  121.               /Hnews
  122.  
  123. /I<my.ini>    Use my.ini as the configuration file.  Default is bnews.ini
  124.               in the same directory as bnews.exe.
  125.  
  126.               /Imy.ini
  127.               /Ix:\path\my.ini
  128.  
  129. /L<logfile>   Create a log file for error messages.  Default is
  130.               bnews.log in the same path as bnews.exe.
  131.  
  132.               /L
  133.  
  134.               To specify the logfile name.
  135.  
  136.               /Lmylog.txt
  137.               /Lx:\path\mylog.txt
  138.  
  139. /O            Read from stdin and write to stdout.
  140.               bnews /cover | bnewsfilter | bnews /cart > art.uue
  141.               bnews /cover | bnewsfilter | bnews /cart | uudeview -io -
  142.               type <group>.get.txt | bnews /cart | uudeview -io i
  143.  
  144. /P<port>      Port number.  Default is 119, this switch will probably
  145.               never need to be used.
  146.  
  147.               /P119
  148.  
  149. /S            Sort the overview of a group by Subject.  Default is not
  150.               to sort the group overview.  This switch only applies in
  151.               overview mode, /cOVER.
  152.  
  153. /V            Verify articles exist on server before downloading begins.
  154.               Useful when downloading multi-part messages.
  155.               This switch only applies in articles mode, /cART.
  156.  
  157. /D            Show debug information.
  158.  
  159.  
  160. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  161. 6.  Operation
  162.  
  163. The program has two modes of operation.  It will download an 1) OVERview
  164. or 2) selected ARTicles from a group.
  165.  
  166. The mode is selected with the /C<command> option.  /cOVER or /cART (case
  167. not important).  OVER and ART are the only two valid commands.
  168.  
  169. For example, to download an overview of alt.binaries.pictures, the
  170. command line would be:
  171.  
  172.   bnews /Cover /Galt.binaries.pictures /Hnews.your.net
  173.  
  174.   The overview will be saved in a file named a.b.pictures.over.txt.
  175.  
  176.   The overview is saved to a text file named <group>.over.txt.  The text
  177.   file is named by the group with ".over.txt" appended at the end of the
  178.   group's name. See "File Naming Mechanism", below.
  179.  
  180.   *NOTE*:  You must provide the group's FULL NAME on the command line or
  181.            in the configuration file.
  182.  
  183. Next, create a.b.pictures.get.txt, with your text editor, which contains
  184. the articles listed in a.b.pictures.over.txt that you want to download.
  185.  
  186. Now run bnews with the /Cart switch to download the articles:
  187.  
  188.   bnews /Cart /Galt.binaries.pictures /Hnews.your.net
  189.  
  190.   Articles will be saved in a file called a.b.pictures.uue.
  191.  
  192. You must have the appropriate tools (uudecode, mime, ...) to extract the
  193. encoded <group>.uue file.
  194.  
  195. When the /V command line option is used (only valid with /cART), bnews
  196. verifies that the all articles exist on the server before downloading
  197. begins.  There are rare occasions when an article(s) listed in the
  198. overview does not exist on the server, so it seems pointless to download
  199. 6/7 to find that 7/7 doesn't exist.  At least, all articles are known to
  200. exist when the download begins, its still possible that article(s) may
  201. be deleted on the server after the download begins, but this is even
  202. rarer in my experience.
  203.  
  204.  
  205. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  206. 7.  File Naming Mechanism
  207.  
  208. <group>.over.txt  - Overview of articles, created by bnews.
  209.                     Always overwritten, truncated.
  210.  
  211. <group>.get.txt   - List of articles to get, created by you.
  212.                     Only read.
  213.  
  214. <group>.uue       - Downloaded articles, created by bnews.
  215.                     Never overwritten, appended.
  216.  
  217. To keep filenames shorter, the following hierarchies are abbreviated:
  218.  
  219.           alt.bbs.doors.binaries.           = a.b.d.b.
  220.           alt.binaries.erotica.             = a.b.e.
  221.           alt.binaries.games.               = a.b.g.
  222.           alt.binaries.multimedia.          = a.b.m.
  223.           alt.binaries.nude.                = a.b.n.
  224.           alt.binaries.pictures.erotica.    = a.b.p.e.
  225.           alt.binaries.pictures.            = a.b.p.
  226.           alt.binaries.sounds.              = a.b.s.
  227.           alt.binaries.warez.               = a.b.w.
  228.           alt.binaries.                     = a.b.
  229.           alt.games.                        = a.g.
  230.           comp.binaries.                    = c.b.
  231.           de.alt.binaries.                  = d.a.b.
  232.           fj.binaries.                      = f.b.
  233.           relcom.comp.                      = r.c.
  234.  
  235.  
  236. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  237. 8.  Problems
  238.  
  239. When pasting to <group>.get.txt, care must be used to preserve the tab
  240. (0x09) characters, otherwise the byte count will not be accurate.  This
  241. does not affect the program's operation.  The byte count is only an
  242. estimate the total number of bytes expected, minus the headers.
  243.  
  244. If the download is interrupted, for any reason, the <group>.get.txt and
  245. <group>.uue files must be reset to the last complete message manually by
  246. you with your text editor.  Follow these two steps:
  247.  
  248.   1.  Load <group>.uue in your text editor, look at the end of the file
  249.       to see if the last message is complete or incomplete.  Most
  250.       complete uuencoded articles end with "end" as the last line.
  251.       Delete any incomplete message at the end of the <group>.uue file.
  252.  
  253.   2.  Reset the <group>.get.txt file by deleting the articles at the
  254.       beginning of the file which were completely downloaded, so that
  255.       when Bnews is run again it will begin downloading the article that
  256.       was incomplete.  You may have to look in <group>.uue to see which,
  257.       if any, article was incomplete.
  258.  
  259.                                 ***IMPORTANT***
  260.             If you don't follow these two steps, the encoded data in
  261.                      <group>.uue will not decode properly!
  262.  
  263.  
  264. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  265. 9.  Future versions
  266.  
  267. Fix the above problems.
  268.  
  269. Add a method to get a list of all news groups from the server.
  270.  
  271. Add feature to keep track of which articles have been downloaded.
  272.  
  273. Improve logging.
  274.  
  275. Suggestions welcome.
  276.  
  277.  
  278. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  279. 10.  Registration
  280.  
  281. Registration for this program is $5.  Send registrations to:
  282.  
  283. Phil Crown
  284. 326 Kinney Drive
  285. Wylie, TX  75098-7725
  286.  
  287. Email:  pcrown@airmail.net
  288. WWW  :  http://web2.airmail.net/pcrown/index.html#bnews
  289.  
  290. Note :  Even if you don't plan to register, send me email saying,
  291.         "Hey, I (like/don't like) Binary News Gatherer!"
  292.  
  293. I'd just like to know if anybody is using the program.
  294.  
  295. Thanks!
  296.  
  297. Phil
  298.  
  299.  
  300. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  301. 11.  History
  302.  
  303. 0.90  Jul 31 96 - First release.
  304.  
  305. 0.91  Aug 17 96 - Touches <group>.get.txt, if it doesn't exist,
  306.                   when downloading an overview.  Helps with
  307.                   cutting/pasting with QEdit, maybe others.
  308.                   Fewer lines from the headers are saved.
  309.                   Shows cps.
  310.                   Shows elapsed runtime.
  311.                   Added cleanover.cmd - REXX script to discard trash
  312.                   from <group>.over.txt.
  313.                   Added /D /I /L /S and /V command line options.
  314.                   More options in .ini file.
  315.  
  316. 0.92  Aug 20 96 - Output to log file is flushed.
  317.                   File Naming Mechanism improved.
  318.                   Article number appended to "423 Bad Article" message.
  319.                   Fixed spelling of Article in Good Article.
  320.  
  321. 0.93  Oct 31 96 - /O switch added - read from stdin and write to stdout.
  322.                   /Cnew - newnews command added.
  323.                   fixed bug in /cnew command that corrupted the date/time
  324.                   in bnews.newstime.
  325.                   fixed bug in socket function when '.' is the first
  326.                   character of a line of an article.
  327.                   Compiled with IBM CSet++ v2.01
  328.                   c2151mt.dll no longer needed
  329.  
  330.